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sides *No. of cylinders* Qn decimal) :Interleave value: On decimal) @FREE Syntax: 
Free [devname] Usage : Displays number of free sectors on a device @GFX 
Syntax: RUN GFX(<funct><args>) Usage : Graphics interface package for 
BASIC09 to do compatible VDG graphics commands (g>G¥X2 Syntax: RUN 
GFX2([path]<functxargs>) Usage : Graphics interface package for BASIC09 to 
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memory @MAKDIR Syntax: Makdir <pathname> Usage : Creates a 
directory file @MDIR Syntax: Mdir [e] Usage : Displays the present memory 
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execution directory path @)RENAME Syntax: Rename <filename> <new rilename> 
Usage : Gives the file or directory a new name (©RUNB Syntax: Runb <i-code 
mrMTnlp> Tka?>p - RASimQ run ttmp narkacrp ^SFTTMF Sv/ntav- <;ptiTnP 

[yy/mm 

Syntax: 

num <§ 

@TMODE 

the operating parameters of the terminal @TUNEPORT Tuneport </tl or /p> 

[value] Adjust the baud value for the serial port @UNLINK Syntax: Unlink 

<modname> Usage : Unlinks moduIe(s) from memory (©WCREATE Syntax: 
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CHRISTMAS GREETINGS 



Bob, Don, Jean-Pierre and lyself would like to wish all 
members a merry Christmas and trust that you and your 
family enjoy a safe and happy new year. li?e would also 
like to thank you for your continued support of the 0S9 
Usergroup and we look forward to your active 
participation in the new year. 

We know just how easy it is to leave the work to somebody 
else especially when we all seem to be governed by the 
higher priorities of life. I aci sure that if every 
member made a commitment to subait iust one small article 
during the coiing year, our newsletter would be enjoyed 
far more by all, You don't have tc be a technical guru 
to present something of interest to others. How about 
telling us what you use your computer for. 
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We'd recomiTiend that ycu get all 15 disks, as the Sources, 
Docs and executable modules of any one programme are not 
necessarily on the same disk. We need to do a fair bit 
of sorting to achieve this, but that will take time. The 
disks are available only in Atari OSK 3.5' format at this 
stage. 



PUBLIC DOMAIN LIBRARr 

Our PD library continues to grow at a steady rate thanks 
mainly to our overseas connections. Our OSK material has 
recently been enlarged by material from the European 
Usergroup. We know that the majority of our members run 
6809 0S9 but for the OSE'ers here is some news. 

The first 15 OSE-PD disks have now been entered into our 
PD-collection. It is the full TOP-ccUecticn collected by 
Wolfgang Ocker in Munich. 

TOP stands for The Os5 Project and contains a lot of 
programmes ported from UNIX to OS5/63000. The TOP-disks 
will be of no use to 6605 users unless you'd be willing 
to (try to) port them to OS-9/6805 yourself. OSK users 
should note that some files might have to be recompiled. 
We do have some reports of trouble with some of the games 
which put too many linefeeds out. Also, the DU (Disk 
Usage) command assumes that all devices have 256-byte 
sectors, which was true for all OSK versions up to 2,3. 
The new version 2.4 allows any size sectors. 

Anyhow, here's the list: 
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Iti THIS EDIT ION 

We present a further chapter of the 'C Tutorial series 
and have some further discussion notes dctmioaded from 
Bitnet by Don Berrie which we think may be cf interest. 

This December edition will have to keep you going until 
February next year as we will not produce one for January 
1552, as has been the practice in previous years, We 
like to take a hclidav too. 



recently which 
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TIPS 

We had a letter from a member in Sydney 

posed a number of questions. We did get to reply even 

though it took a few weeks, sorry about that, my fault. 

Anyway, a couple of items may be of general interest. 

Ouestion:- 

I know that the utility 'error" will report the meaning 

of the error number, but I want this message to come up 

without having to type 'error txxx", can you help, 

Answer;- 

We are using a patched version of the Level 1 command 

"printerr" which works just fine. Printerr needs to be 

in your 0S9Boot file and called from the "startup" script 

file. It looks for the text file "errmsg" in the /dd/SYS 

directory and reports the meaning of every error number 

(provided that the error number and text is in the 

"errmsg" file. The patch file is available in the PD 

library, 

Ouesticn:- 
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Is there any vay of telling if a VEF picture file is in 

squashed format? 

Ansver;- 

The first character in a Standard VEF file is 00 vhile 

the first character in a squashed (compressed) file is 

80. Info from M.V. Canvas version 2 iiianual. 

Question:- 

Is there any way of telling the size of a single file? 

Answer; - 

While the "dir -e" comjiand vili report the size (in hex) 



of every file in the current directory, we are not aware 
of a utility to report the size of an individual file. 
Perhaps somebody can help vith this one. (Bob Devries 
wrote a utility named "fileinfo' which reports a lot of 
info about the file as well as checking the file 
integrity; perhaps we can persuade him to produce a 
simplified version for "filesize" ?? 

Until next year, Happy computing and Happy holiday. 

Gordon. 



ooooooooGoOOGOOQGOQQocooooooQc 



Usina Kevin Darlinc's GFa2 



bv Bob De^ 



Kevin Darling, the somewhat famous guru of the 
American 0S9 community, has written a replacement GFX2 
module for users of Basic09. The version I have, which 
also appears in our PD library, is some 122 bytes longer 
than the original module, but has quite a few extra 
commands, when IDENTed, this new GFX2 gives a CRC of 
$171CCE and a length of $949, whereas the old version has 
a CEC of $C940AD and a length of $3CA. It has only one 
failing, the FILL command is missing! Ie anyone has a 
later edition of this prcgramme, please don't keep us in 
the dark! 

I have wrirten a little BasicG9 programme to show you 
how to use the pulldown menus and mouse controls with 
keviu's GFX2. It is really simple to use, and does not 
require the use of complex variable types (structures). 
The programme opens a window (on /w as usual), which it 
then makes into a 40 x 24 graphics window using the DVSET 
call. After turning the cursor off, and selecting the 
window, the pulldown menu calls are used. 

First, the main menu bar at the top of the window. 
This information is rarely seen, unless another window is 
opened on top of ours. Then the two titles for the 
pulldown menus are passed to the window manager, along 
with the numbers which they are to be identified by (33 
and 34). Next come the items in the two menu pulldowns, 
With their identifiers, and whether they are enabled or 
not. You'll notice that the Format choice is carefully 
disabled, so you can't accidentally format something 
important! After all the information has been passed to 
the window manager (tfindint), we issue the call '^nSet' 
to tell it to draw the screen. Next, we set up the mouse 
handler with the 'SetKouse' call, and pass it values of 
3,1,1 which are the scanrate, the timeout, and the 
autofoUow values, 

The programme Dexr selects the pointer type using 
'GCSer', and it chooses an arrow. Now we get to a loo? 
which allows the selection cf the pulldown. Notice, that 



the window manager does the actual pulldown for you and 
gives back to the programme the menu^id and menu_item of 
the selected item. On the basis of that, the programme 
goes to the appropriate subroutine and does what the 
pulldown suggests. Note, I have not included any error 
trapping, so if any of the commands (on the lines 
starting with 'Shell') are not either in memory or in the 
current execution directory, the programme will quit. 

So you can see that it is really easy to make ycur 
Gvn pulldown window system. Note that you do not need to 
run this from 'MultiVue'. but vou must have 'windint' in 



your 0S9Boot file. If vou don't 



it will not work. 
Regards, Bob Devries 



FEQCEDUHE pulldown 
0000 
0007 
0013 
OOIF 
002B 
0037 
0042 
004D 
0059 
0078 
0082 
008A 
0091 
0058 
009F 
OOAC 



00E5 



lOB 

1 1 i 



DIM ?ath:BYTE 

DIM wd(3):STRING 

DIM mI(3);STRING 

DIM a2(2):STSING 

DIM winstr:STEINGf32l 

DIM MIdjisk,KIdjem:ISTEGER 

DIM Disable, Enable; INTEGER 

DIM a:STEING[ll 

DIM valid, f ire, m.x, my, area, sx,sy; INTEGER 

DIM menu_id,menu item:INTEGEE 

KIdJisk^33 

MIdJem=34 

DisQble=0 

Enable=I 

OPEN #path,Vw";UPDATE 

RUN Qetdevname|path,winstr) 

RUN gfx2(path/DVSet\8,0,0,40,24,0,I,I) 

RUN gfx2(path, 'select") 

RUN gfx2(path/curoff") 

RUN gfx2(path,"Title",wd,"Tools",34,I0,2) 

RUN gfx2(p3th,"MenuV,wd,,I, "Disk", Mid Disk 



8, 4, ml, Enable) 
OUS RUN 
0I8F RUN 



1B6 



:fK2(path/ItemVml,I,"Dir %Enablel 
RUN Qfx2(path/Item",ml,2/Free ", Enable) 
RUN afx2(path,«Item",El,3,"PWD «, Enable) 
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OIDD EU8 gfx2(path, "Item", ul, 4, "Foriaf, Disable) 

0204 m gfx2(path,'»8nu',»d,2,"MeioryMlId_Meii, 

6, 2, i2, Enable) 



023B 
0261 

0287 
02A1 
C2BF 
02D8 
02DA 
02F1 

area,sx,sy 
0326 
0340 
035D 
0369 
036D 
03bF 
037B 
037F 
0381 
03aD 
0391 
0393 
0395 

0399 100 
e-AD 
03B3 

03B5 209 
03CF 

03D1 300 
03E3 

03E5 400 
03F2 
0401 
0405 

0407 500 
0414 
0424 
0428 



m gfx2(path/Iteii',ii2,l,'HFree', Enable) 

RUM Qfx2(path,"Itei', 112, 2, "Procs", Enable) 

EUH gfx2(path/WnSetM,yd) 

m gfx2(path/setiiouse',3,l,l) 

RUN gfx2(path,'gcset',$CA,i) 

LOOP 

Rl'S gfx2(path,'onEOUEe',0) 

RUN gfx2(path/ic!ase', valid, fire, EX, Ev, 

IF validOO AND tLre=i AND cree=I THEE 

RUN gfs2(path/qet£el%iue!iU it,^e^c i 

IF i^eau_id=2 THEN 
GOTO 100 

ENDIF 

IF Beai]_id=33 THEN 
GOSUB 200 

ENDIF 

IF ieiiiijd-34 THEN 
GOSUB 300 

ENDIF 
ENDIF 
ENDLOO? 

SUN Qfx2!I/seiect'') 
CLOSE Ipath 
END 

ON meiii!_ite!r GOSUB 400.500,600,700 
RETURN 

ON inenoJteE GOSUB 300,900 
RETURN 

PRINT tFath,CER$fl2) 
SHELL "dir" + ")nwiQstr 
GOSUB 1000 
RETURN 

PRINT #path,CeR5(12) 
SHELL "free^'N^+wmstr 
GOSUB 1000 
RETURN 



042A 600 PRINT #path,CHR$(121 

0437 SHELL "pwd*i*)*lwiEStr 

0446 GOSUB 1000 

044A RETURN 

044C 700 PRINT fpath,CERS(12) 

0459 RETURN 

04dB 800 PRINT fpath,CHR$iI2! 

0468 SHELL "]nfree"+">4wiii£tr 

04/9 GOSUB 1000 

u47D RETURN 

04/F 500 PRINT fpath^CHRSin) 

u4BC SHELL "prccs^^'/'^winstr 

049D GOSUB 1000 

04hI RETURN 

HK] 1000 ^HILE r-"' DC 

0402 m iGkey[?ath,&l 

04C1 ENDwHILE 



e4C: 


sETyEH 




PSOCEDUI 


E getdevnaie 




0006 


TYPE register£:cc,e,b,dF:ByTE; x, 


y,u;IKTEC-EE 


0025 


DIM reoE:reoister£ 




002E 


PASAM spath-.BYTE 




0035 


PAEAK ifinGa!,:STSI(!G[32l 




0041 


DIM i:IliTEGEE 




0048 


DIM callcode:BY7E 




094F 


re:E,a=vparh 






i '-■ w w . i.- Y ■. ■;j 




0057 


regc.v-ADDSU'ionaEi 




CO'5 


cailceae=53D 




C07B 


SUS sv5call(callcode,regEi 




oosc 


FOE i-1 TO 32 




009C 


EXITIF HID5(»'iQr!3!P„i.l!)CEi?(I2ai 


THEli 


OOAF 


tfiEnai^'/'+LEFTSU'innam,!- 




l!tCHE$ 


AEC(KI['$!»inna!ii,i,l)i-12S) 




OODl 


EDDEVir 




O0S5 


SEXT i 




OOEC 


m 





CGOCOOOOQOOOOOOOOOOOOGCOOOOOOO 

A C Tutorial 
Chapter 5 - Functions and variables 



OUR FIRST USER DEFINED FUNCTION 

Load and exanine the file SUMSORES.C for an exanple 
of a C prograii with functions. Actually this is not the 
first function we have encountered because the "lain" 
program we have been using all along is technically a 
function, as is the "printf function. The "printf 
function is a library function that vas supplied with 
your coBpiler, Notice the executable part of this 
prcgraE, It begins with a line that siaply says 
"header! )\ which is the way to call any function. The 
parentheses are required because the C coF,piler uses them 



to determine that it is a function call and not siEply a 
displaced variable. 

^hen the prograin coir.es to this line of code, the 
function named "header* is called, its stateiaents are 
executed, and control returns to the statement following 
this call. Continuing on we come to a "for" loop which 
will be executed 7 times and which calls another function 
named "square" each time through the loop, and finally a 
function named ''ending" will be called and executed. For 
the moment ignore the "index" in the parentheses of the 
call to "square", we have seen that this prograE 
therefore calls a header, 7 square calls, and an ending. 
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Nov ve need to define the functions. 
DEFINING THE FUNCTIONS 

Following the main program you will see another 
program that follows all of the rules set forth so far 
for a "main" program except that it is named "header! )". 
This is the function which is called from within the main 
program. Each of these statements are executed, and when 
they are all complete, control returns to the main 
program, The first statement sets the variable "sum" 
equal to zero because we will use it to accumulate a sum 
of squares. Since the variable "sum" is defined as an 
integer type variable prior to the main program, it is 
available to be used in any of the following functions. 
It is called a ^global" variable, and it's scope is the 
entire program and all functions. 

More will be said about the scope of variables at the 
end of this chapter. The next- statement outputs a header 
message to the monitor. Program control then returns to 
the main program since there are no additional statements 
to execute in this function, It should be clear to you 
that the two executable lines from this function could be 
moved to the main program, replacing the header call, and 
the program would do exactly the same thing that it does 
as it is now written. This does not minimize the value 
of functions, it merely illustrates the operation of this 
simple function in a simple way. You will find functions 
to be very valuable in C programming. 

PASSING A VALUE TO A FUNCTION 

Going back to the main program, and the "for" loop 
specifically, we find the new construct from the end of 
the last lesson used in the last part of the for loop, 
namely the "indexH". You should get used to seeing 
this, as you will see it a lot in C programs. In the 
call to the function "square", we have an added feature, 
namely the variable "index" within the parentheses. This 
is an indication to the compiler that when you go to the 
lunction, you wish tc take along the value of index to 
use m the execution of that function. Looking ahead at 
the function "square", we find that another variable name 
is enclosed in its parentheses, namely the variable 
"number"- This is the name we prefer to call the 
variable passed to the function when we are in the 
function. Ve can call it anything we wish as long as it 
follows the rules of naming an identifier. 

Since the function must know what type the variable 
is, it is defined following the function name but before 
the opening brace of the function itself. Thus, the line 
containing "int number;" tells the function that the 
value passed to it will be an integer type variable, 
if/ith ail of that out of the way, we now have the value of 
index from the main program passed to the function 
'square", but renamed 'number", and available for use 
within the function. Following the opening brace of the 



function, we define another variable "numsq" for use only 
within the function itself, (more about that later) and 
proceed with the required calculations. We set "numsq" 
equal to the square of number, then add nuisq to the 
current total stored in 'sum". Remember that "sum += 
numsq" is the same as "sum = sum + numsq" from the last 
lesson, ife print the number and its square, and return 
to the main program. 

MORE ABOUT PASSING A VALUE TO A FUNCTION 

ii/hen we passed the value of "index" to the function, 
a little more happened than meets the eye. We did n^t 
actually pass the value of index to the function, we 
actually passed a copy of the value. In this way the 
original value is protected from accidental corruption by 
a called function. Ve could have modified the variable 
"number' in any way we wished in the function "square", 
and when we returned to the main program, "index" would 
not have been modified. We thus protect the value of a 
variable in the main program from being accidentally 
corrupted, but we cannot return a value to the main 
program from a function using this technique. We will 
find a well defined method of returning values to the 
main program or to any calling function when we get to 
arrays and another method when we get to pointers. 

Until then the only way you will be able to 
communicate back to the calling function will be with 
global variables. We have already hinted at global 
variables above, and will discuss them in detail later in 
this chapter. Continuing in the main program, we come to 
the last function call, the call to "ending". This call 
simply calls the last function which has no local 
variables defined. It prints out a message with the 
value of "sum" contained in it to end the program. The 
program ends by returning to the main program and finding 
nothing else to do. Compile and run this program and 
observe the output. 

NOW TO CONFESS A LITTLE LIE 

I told you a short time ago that the only way to get 
a value back to the main program was through use of a 
global variable, but there is another way which we will 
discuss after you load and display the file named 
SQUARES. C. In this file we will see that it is simple to 
return a single value from a called function to the 
calling function. But once again, it is true that to 
return more than one value, we will need to study either 
arrays or pointers. In the main program, we define two 
integers and begin a "for" loop which will be executed 8 
times. The first statement of the for loop is "y = 
squ(x);", which is a new and rather strange looking 
construct. From past experience, we should have no 
trouble understanding that the "squ(x)" portion of the 
statement is a call to the "squ" function taking along 
the value of "x" as a variable. Looking ahead to the 
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function itself we find that the function prefers to call 
the variable 'in" and it proceeds to square the value of 
"in" and call the result "square". 

Finally, a nev kind of a statement appears, the 
"return" statement. The value within the parentheses is 
assigned to the function itself and is' returned as a 
usable value in the sain prograi. Thus, the function 
call "squ(x)" is assigned the value of the square and 
returned to the main program such that "y" is then set 
equal to that value, If "x" were therefore assigned the 
value 4 prior to this call, "y" would then be set tc 16 
as a result of this line of code. Another wav to think 



of this is to consider the grouping 



characters 



"squlxl" as another variable with a value that is the 
square of ">:", and this new variable can variables be 
used any place it is legal to use a variable of its type. 
The values of "x" and "y" are then printed out. 

To illustrate that the grouping of "squlx)' can be 
thought of as just another variable, another "for" loop 
is introduced in which the function call is placed in the 
print statement rather than assigning it to a new 
variable. One last point must be made, the type of 
variable returned iTiUst be defined in order to make sense 
of the data, but the compiler will default the type to 
integer if none is specified. If any other type is 
desired, it iiust be explicitly defined. Hov to do this 
will be demonstrated in the next exaiiple program. 
Coiipile and run this prograii. 

FLOATING POINT FUNCTIONS 

Load the prograE FLOATSQ.C for an example of a 
function with a floating point type of return. It begins 
by defining a global floatiiig point variable we will use 
later. Then in the "main" part of the program, an 
integer is defined, followed by two floating point 
variables, and then by two strange looking definitions. 
The expressions "sqrd" and '''glsqriM look like function 
calls and they are. This is the proper way in C to 
define that a function will return a value that is not of 
the type "int^ but of some other type, in this case 
"float". This leils the compiler that when a value is 
returned from either of these two functions, it will be 
of type "float". Now refer to the function "sqr" near 
the center of the listing and you will see that the 
function name is preceded by the name "float". This is 
an indication to the compiler that this function will 
return a value of type "float" to any program that calls 
it. 

The function is now compatible with the call to it. 
The line following the function name contains "float 
inval;", which indicates to the compiler that the 
variable passed to this function from the calling program 
will be of type "float". The next function, namely 
"glsqr", will also return a "float" type variable, but it 
uses a global variable for input. It also does the 
squaring right within the return statement and therefore 



has no need to define a separate variable to store the 
product, The overall structure of this progran should 
pose no problem and will not be discussed in any further 
detail. As is customary with all example programs, 
compile and run this program. There will be times that 
you will have a need for a function to return a pointer 
as a result of some calculation, There is a way to 
define a function so that it does just that. We haven't 
studied pointers yet, but we will soon. This is just a 
short preview of things to cone. 

SCOPE OF VAIIABLES 

Load the next program, SCOPE. C, and display it for a 
discussion of the scope of variables in a program. The 
first variable defined is a global variable "count" which 
is available to any function in the program since it is 
defined before any of the functions. In addition, it is 
always available because it does not come and go as the 
program is executed. (That will make sense shortly,) 
Farther down in the program, another global variable 
named "counter" is defined which is also global but is 
not available to the main program since it is defined 
following the main program, A global variable is any 
variable that is defined outside of any function. Note 
that both of these variables are sometimes referred to as 
external variables because they are external to any 
functions. 

Return to the lain program and you will see the 
variable "index" defined as an integer. Ignore the word 
"register" for the moment. This variable is only 
available within the main program because that is where 
it is defined. In addition, it is an "automatic" 
variable, which means that it only comes into existence 
when the function in which it is contained is invoked, 
and ceases to exist when the function is finished. This 
really means nothing here because the main program is 
always m operation, even when it gives control to 
another function. Another integer is defined within the 
"for" braces, namely "stuff". Any pairing of braces can 
contain a variable definition which will be valid and 
available only while the program is executing statements 
within those braces, The variable will be an "automatic" 
variable and will cease to exist when execution leaves 
the braces. This is convenient to use for a loop counter 
or some other very localized variable. 

MORE ON "AUTOMATIC" VARIABLES 

Observe the function named "headl". It contains a 
variable named "index", which has nothing to do with the 
"index" of the main program, except that both are 
automatic variables, tfhen the program is not actually 
executing statements in this function, this variable 
named "index" does not even exist, fefhen "headl" is 
called, the variable is generated, end when "headl" 
completes its task, the variable "index" is eliminated 
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completely from existence. Keep in fflind however that 
this does not affect the variable of the same name in the 
main program, since it is a completely separate entity. 
Automatic variables therefore, are automatically 
generated and disposed of when needed. The important 
thing to remember is that from one call to a function to 
the next call, the value of an automatic variable is not 
preserved and must therefore be reinitialized. 

WHAT ARE STATIC VARIABLES? 

An additional variable type must be mentioned at this 
point, the "static" variable. By putting the reserved 
word "static" in front of a variable declaration i^ithin a 
function, the variable or variables in that declaration 
are static variables and will stay in existence from call 
to call of the particular function. By putting the same 
reserved word in front of an external variable, one 
outside of any function, it makes the variable private 
and not accessible to use in any other file. This 
implies that it is possible to refer to external 
variables in other separately compiled files, and that is 
true. Examples of this usage will be given in chapter H 
of this tutorial. 

USING THE SAME Ml AGAIS 



Refer to the 
another definition 
tiiough "count"* ha 
variable, it is per 
this function. It 
nothing to do with 
and causes the glob 
function. This a 
existing functions 
used for variables 
no conflict. You 
that interface with 



function named "head2V It contains 

of the variable named "countV Even 
s already been defined as a global 
fectly all right to reuse the name in 
is a completely new variable that has 
the global variable of the same name, 
al variable to be unavailable in this 
Hows you to write programs using 
without worrying about what names were 

in the functions because there can be 
only need to worry about the variables 

the functions. 



variables available, will simply ignore the word 
'register" and run normally, keeping all variables in 
memory. Register variables are only available for use 
with integer and character type variables. This may or 
may not include some of the other integer-like variables 
such as unsigned, long, or short. Check the 
documentation for your compiler. 

VHERE DO I DEFINE VARIABLES? 

Now for a refinement on a general rule stated 
earlier. Vhen you have variables brought to a function 
as arguments to the function, they are Gefi]>ed 
immediately after the function name and prior to the 
opening brace for the program. Other variables used in 
the function are defined at the beginning of the 
function, immediately following the opening brace of the 
function, and before any executable statements. 

STANDARD FUKCTION LIBRARIES 

Every compiler comes «ith some standard predefined 
functions which are available for your use. These are 
mostly input/output functions, character and string 
manipulation functions, and math functions, k'e will 
cover most of these in subsequent chapters. In addition, 
most compilers have additioDal functions predefined rhat 
are not standard but allow the programmer to get the most 
out of his particular computer, In the case of the IBM- 
PC and compatibles, most of these functions allow the 
programmer to use the BIOS services available in the 
operating system, or to write directly to the video 
monitor or to any place in memory. These will not be 
covered in any detail as you will be able to stady the 
unique aspects of your compiler on your own. Hany or 
these kinds of functions are used in the example programs 
in chapter 14. 

WHAT IS RECURSION? 



W5AT IS A REGISTER VARIABLE? 

Now to fulfill a promise made earlier about what a 
register variable is. A computer can keep data in a 
register or in memory. A register is m.uch faster in 
operation than memory but there are very few registers 
available for the programmer to use, If there are 
certain variables that are used extensively in a program, 
you can designate that those variables are to be stored 
in a register if possible in order to speed up the 
execution cf the program. Depending on the computer and 
the compiler, a small number of register variables may be 
allowed and are designated by putting the word "register" 
in front of the desired variable. 

Check your compiler documentation for the 
availability of this feature and the number of register 
variables. Most compilers that do not have any register 



Recursion is another of those programming techniques 
that seem very intimidating the first time you come 
across it, but if you will load and display the example 
program named RECURSOLC, we will take all cf the mystery 
out of it. This is probably the simplest recursive 
program that it is possible to write and it is therefore 
a stupid program in actual practice, but for purposes of 
illustration, it is excellent. Recursion is nothing more 
than a function that calls itself. It is therefore in a 
loop which must have a way cf terminating. In the 
program on your monitor, the variable ''index" is set to 
8, and is used as the argument to the function 
"countjn". The function simply decrements the variable, 
prints it out in a message, and if the variable is not 
zero, it calls itself, where it decrements it again, 
prints it, etc. etc. etc. 

Finally, the variable will reach zero, and the 
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function will not call itself again. Instead, it will 
return to the prior time it called itself, and return 
again, until finally it will return to the main program 
and will return to DOS. For purposes of understanding 
you can think of it as having 8 copies of the function 
"countjn" available and it simply called all of them one 
at a time, keeping track of which copy it was in at any 
given time. That is not what actually happened, but it 
is a reasonable illustration for you to begin 
understanding what it was really doing. 

WHAT DID IT DO? 

A better explanauon of what actually happened is in 
order. Vhen you called the function from itself, it 
stored all of the variables and all of the internal flags 
it needs to complete the function in a block somewhere. 
The next tiDe it called itself, it did the same thing, 
creating and storing another block of everything it 
needed to complete that function call. It continued 
making these blocks and storing them away until it 
reached the last function when it started retrieving the 
blocks cf data, and using them to complete each function 
call. The blocks were stored on an internal part of the 
computer called the "stack". This is a part of memory 
carefully organized to store data just as described 
above. 

It IS beyond the scope of this tiitorial to describe 
the stack in detail, but it would be good for your 
programming experience to read some material describing 
the stack. A stack is used in nearly all modern 
ccsputers for internal housekeeping chores. In using 
recursion, you may desire to write a program with 



indirect recursion as opposed to the direct recursion 
described above. Indirect recursion would be when a 
function "A' calls the function "B", which in turn calls 
"A', etc. This is entirely permissible, the system will 
take care of putting the necessary things on the stack 
and retrieving them when needed again, There is no 
reasoii why you could not have three functions calling 
each other in a circle, or four, or five, etc. The C 
compiler will take care of all of the details for you. 

The thing you must remember about recursion is that 
at soEe poinr, something must go to zero, or reach some 



predefined point to terminate the loop. If not, you will 
have an infinite loop, and the stack will fill up and 
overflow, giving you an error and stopping the program 
rather abruptly. 

ANOTHER EMMPLE OF RECURSION 

The program named BACKVARD.C is another example of 
recursion, so load it and display it on your screen. 
This program is similar to the last one except that it 
uses a character array. Each successive call to the 
function named "forward andjackward" causes one 
character of the message to be printed. Additionall-y, 
each tiu the function ends, one of the characters is 
printed again, this time backwards as the string of 
recursive function calls is retraced. Don't worry about 
the character array defined in line 3 or the other new 
material presented here. 

After you complete chapter 7 of this tutorial, this 
program will make sense. It was felt that introducing a 
second example of recursion was important so this file is 
included here. One additional feature is built into this 
program. If you observe the two calls to the function, 
and the function itself, you will see that the function 
name is spelled three different ways in the last few 
characters. The compiler doesn't care how they are 
spelled because it only uses the first 8 characters of 
the function name so as far as it is concerned, the 
function is named MorwardJ. The remaining characters 
are simply ignored. If your compiler uses more that 8 
characters as being significant, you will need to change 
two of the names so that all three names are identical. 
Compile and run this program and observe the results. 



PROGEAMHItlG EXERCISES 

1. Rewrite TEMPCONV.C, from an earlier chapte; 
the temDerature calculation to a function. 



and move 



2. k'rite a program that writes your name on the monitor 
10 times hy calling a function to do the writing. 
Move the called function ahead of the "main'' function 
to see if vour comDiler will allow it. 



oooooooQOoOGOOOOQOOGooooGOGQOc 

An Index of Rainbow 0S9 Articles 

compiled by Bob Bevries 

January - December 'S7 

January 1987 page 160 ElSSable 0S5 - Debunking some 0S9 myths. 

Get Comfortable with 0S9 - Tutorial. A good introduction Dale L. Puckett 

for beginners. 

Nancy Ewart February 1987 page 26 

Kurder at the Hotel CoCo - Game A Rainbow staff imposter 
January 1937 page 193 is bent on mayhem! 
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Dale Lear 

February 1987 page 190 

KlSSable 0S9 - A level II report. 

Dale L. Puckett 

February 1987 page 204 

Pipes and Filters - TutoriaL The siisunderstood features, 

Bruce S. Warner 

March 1937 page 186 

Barden's Buffer - Sailing off to C. 

Williai Barden, Jr. 

Karch 19S7 page 196 

KlSSable 0S9 - Bootstrapping iiany systeiriE. 

Dale L, Puckett 

March 1987 page 19-1 

0S9 Level II - 0S9 programing. Finding your way in the 

new svste]^. 

Pete: Dibble 

April 1937 page 197 

KlSSable 0S9 - Back to the beginning. 

Dale L. Piickett 

April 1987 page 152 

MeiTiory Manageiient - Understanding 0S9's r^eiory systes. 

Peter Dibble 

May 19B7 page 196 

KlSSable 0S9 - Setting the stage for 0S9 Level II, 

Dale L. Puckert 



Basic09, 
Rick Adans 

July 1987 page 100 

A Computer's Ancient Native Language - Tutorial, A look 

at soie profound magic for the CoCo. 

Peter Dibble 

July 1987 page 163 

Bits and Bytes of Basic - Basic09 and Level 11; Focusing 

on modules, 

Richard k^hite 

July 1987 page 15" 

KlSSable 0S9 - l\n 0S9 convert speaks out. 

Dale L. Puckett 

August 1987 page 157 

KlSSable 0S9 - Controller attacks halt line problem. 

Dale L. Puckett 

August 1987 page 163 

The Problem with BaEic09 - 0S9 Meniory. Improving the 

Editor procedure. 

Peter Dibble 

September 1987 page 160 

KlSSable 0S9 - Primitive drawing tools. 

Dale L. Puckett 

September 1967 page 170 

Basic09 isn' fast enough - 0S9 Programming. Assembly 

language can be fun. 

Peter Dibble 



May 1987 page 194 

Pause for Thought - Avoid mistake lockijps with a handy 

pause command. 

Paul Ladcucer 

May 1987 page 191 

The Advantage of Processes - 'Slicing' programs for 

greater memory . 

Peter Dibble 

June 1987 i;aae H^ 

Fish or Pheish? - Education. Basic09 helps with phoneme 

recognition. 

Del Turner 

June 1987 page 162 

KlSSable 0S9 - Shooting for a standard. 

Dale L. Puckett 

June 1987 page 15^. 

Exploring Level II - A looke at nesf features from 



October 1987 page 176 

KlSSable 0S9 - Unlock graphics potential. 

Dale L. Puckett 

October "1987 page 164 

GS9 Programming - Using compressed files. 

Peter Dibble 

tiovember 1937 page ISO 

KlSSable 0S9 - The evoluricn continues. 

Dale L, Puckett 

December 19B7 page ISO 

KlSSable 0S9 - Putting data structures on the drawing 

board. 

Dale L. Puckett 

December 1987 page 168 

0S9 Programming - Saving and restoring graphics screens. 

Peter Dibble 
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CoCo-Link 
CoCo-Link is an excellent magazine to help you with the RSDOS side of the Colour Computer. It is a bi-monthly Eacazine 
published by Mr. Robbie Dalzell. Send your subscriptions to: 

CoCo-Link 

31 Nedlands Crescent 

Pt. Soarlunga Sth. 

South Australia 

Phone: (08) 3861647 



Things we'd like to have for Christmas 



In recent times, we have talked about "wish-lists" for 

our favourite computer. Here, we present one such list 

from Tim Eientzle, one of the more erudite of the 
contributors to the Internet 0S9 List, 



I have a few ideas for programs I'd like to see written. 
Not sure how many of these, if any, I might write myself, 
but all seem like useful things. They aren't necessarily 
flashy programs with sophisticated graphics and sound, 
etc, but they're solid useful programs that would help 
make life a lot more convenient. 

- Interactive Disassembler. A friend of mine wrote a 
disassembler for his Atari ST that had some really good 
ideas. It displayed a disassembly on the screen, and you 
could scroll up and down through it. You cculd press a 
key on some line, and everything from there down would be 
displayed in a different format, such as hex, ASCII, etc. 
By going through and interactively inserting these 
markers, you could fairly quickly get a fairly good 
disassembly of an area. Add in the ability to name 
labels interactively, and to attach comments to any line, 
and you'd have one amazingly convenient disassembler, 

- Termcap/Curses library. Some are floating around ?D, 
but a "good' library would be very useful. Adding 
support for things like overlays, menus, etc, on any 
terminal would make lots of programs a lot easier. 



" file picker 



- File picker, editor widgets. A "good 
dialogue takes a long time to do well. Ditto for a small 
editor (say, up to 32k max). Bundled into a library 
(maybe even with the above Termcap/Curses?), it would be 
extremely useful. 



several. Should allow insertions and/or deletions, evjn 
within a module (automatically updating the module size 
and such), as well as the standard operations. 

- Disk Editor. A "good** disk editor s^^ould do more than 
just display sectors. It should let you walk through the 
directory heirarchy, let you examine and modify file 
descriptor sectors (not as a hex dump, either), LSNO, 
mark sectors as allocated/unallocated in the bitmap, 
move, rename, delete files, etc. 

- Bootfile editor. Should allow convenient mouse-driven 
insertion and deletion of modules and devices, (i.e. I 
insert a device, the editor adds the descrLpior and the 
driver and manager, if necessary) Also should allow 
editing of xmcde and tmode setnngs in descriptors. May 
or may not include ability to do binary editing of 
individual modules. 

- Spreadsheet. Lotus and the like are messy. Something 
easy to use, easy to program, with some nice user- 
oriented features. 

Graphing, data analysis. Someone using Lotus 
complained to me the other day that there should be a way 
to grab a point on the graph and have the number in the 
spreadsheet change to match. This same person was trying 
to do some curve-fitting as well, which Lotus does not 
have any convenient facilities for. A nice program which 
can read in tables of data and display graphs and/or 
lists of numbers, which are easily changed, graphed in 
different fashions, etc, could be quite useful some days. 
If it could also graph equations, etc, that could be even 
better. 



- Memory allocation library. A handle-based memory 
manager which can do heap compaction, and can later be 
extended to support virtual memory concepts would be a 
great project for some of you CS types, (grin) Basic 
handle-based memory management is easy to do, but there 
are tricks when you consider locking blocks of memory 
etc. mallocO just isn't enough somedays. 

- Binary Editor. A good binary file editor would show 
vour file in hex and/or ASCII, or even a combination of 



- Mail Agents. I've seen several different programs 
that attempt to do things like log on to CIS, download 
ail your mail, and log off immediately, leaving the mail 
in a file where you can read it at your leisure. 
Ideally, this should of course feed into the existing 
mail system, i.e. I should be able to send mail on my 
computer to "72276, 1135?compuserve^ and have it be 
spooled to a special directory. Once a week or so, some 
program is run by "cron" which automatically logs into 
CIS, mails all my messages, downloads messages to me, 
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etc. The net effect is that my mail system on my home 
computer gateways onto CIS, Delphi, UUCP, the Unix system 
at school etc, etc. Add in full support for the CIS, 
Delphi forums, and you've got some customers, This would 
require a lot of work, some sort of sophisticated 
scripting language, etc, etc. 

- "Smart" mail filters. Especially on those days I log 
in to find 80 messages from the mailing list, along with 
10 other messages, I really wish this Unix system 
supported several mailboxes for each user, with some 
prograii which could automatically do some filtering for 
me, putting all mailing list messages into an inbox 
called "CcCoV etc, etc, 



reader. A nice, mouEe-driven mH reader would 



windows: one showing a list of messages, another showing 
the messages. Click on a message to read it, 
buttons/menus to reply to the siessage, move it to a mail 
folder, etc. If "news" were available through the same 
program, it would be even better: I see three types of 
messages: private person-to-person messages (mail), 
forum messages available to a narrow group of subscribers 
(i.e. I don't want anybody on my machine to be able to 
respond to Delphi Forum messages through my account), and 
public-distribution (news!. Having all three available 
through one program interface would be quite convenient. 

As new machines come out, and more folks have experience 
with CoCo windows, the need for interesting ideas grows. 
It'hat proarams do vou think would make vour life easier? 



be so convenient, esi^ec 



with the above 



iWO 



Tim 



le 



OOOOOOOOCC'JlH 



mn 



OOOOOOCOOC 



tfPShel Product Description 



The Australian 0S9 User Group does not normally publish 
advertising material, and this article seems remarkably 
like just that! However, in the interests of making 
relevant information available to our readers, here is a 
product description of &/PShei from ColorSystems, in the 
USA. 



Shell in either another window or in an overlay window. 

Since &!?Shel is a Graphical User Interface (GUI), it will 
be cumbersome for experianced QS5 Users who prefer to 
access Gb5 at the Command Line level. I originally 
desicned SnlPEhel tc be 



I i iiiii: i ^ 



^■PShei is a Graphics Shell for GS9 Level 2 (0S91 and the 

the 

Iti- 

Bar" 

Bar 

ing the mouse cursor tc 

clickina the left mouse 



Color Computer 3 (CoCo31, It is designed similarly to 
Graphics Shell most of you are used to looking at, Mu 
Vue's GShell, in that the Main Screen has a "Menu 
across the top of the window. Access to ell Menu 
functions is Ecconrlished by poi! 
the Menu Bar "Menu Name" and 



useful for novice 0S9 
Users who wish tc use their system for word Processing, 
and for any 0S5 user who has the need to set up a 
"Turnkey'' Vord Processing system for use by people who 
can't even spell "QS^". But since the inspriation for 
WPShel was the highly successful DECB based word 
processor, Ty-I29, former TV-128 users may find WPShel 
enjoyable to use, In fact, early reviewers of l^FShel have 
even referred tc it as an ''OS^ clone of T^'-128V 



button. There are four Menu Flames on the Menu Bar, plus 

the Tandy Menu Icon. The "Exit Program" icon, a la One VERi important thing to realize about ^'PShel is that 



GShell , is also present. 

When you click on a Menu Name, a "pull down" menu is 
displayed under the Menu Name. To select one of the pull 
down "Menu Items", you pull down the mouse cursor to the 
item you want and click the left mouse button. Various 
actions then occur, based on the specific Menu Item ycu 
selected. Overlay windows are used frequently, with input 
normally either via keyboard entry or mouse click. Most 
of the more commonly used functions are also accessible 
via an ALT-key command sequence. 

WPShel got it's name because all Menu Names and their 

associated Menu Items are all Word Processing oriented, 

There are four Menu Names, ''Document^ "Print", 

"Speller', and "Utility". Virtually all basic Shell 

functions are available via the Menu Items, and just in 

case there is an GS5 command you need to execute which is 

not a Menu Item, there is a facility to fork the standard 



s -a SHELL. 



is not an all encompassinq Word 



Processor, The major functions such as the Editor and the 
Text Formatter are not performed directly by WPShel. They 
are handed over to an external module in a "forked" 
process. Big reasons why I designed WPShel in this manner 
is that 



1) Most people are already familiar with an editor and 
HATE to use any other editor, WPShel allows you to use 
whichever editor you already have and like to use. It 
was tested with VED, ED, SLED, EDIT, T/S Edit and 
DYMSTAS, with VED being the author's editor of choice 
since it will run in any window type and almost any 
window size. 

2! There are already several excellent editors and text 
formatters available for 0S9,, many Public Domain or 
Shareware. 
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3) 0S9 is structured such that one program is limited to 
a 64K address space, but the concept of forking a child 
process to perform work is simple and easy to do. 

WPShel is a strong competitor to DynaStar and an even 
stronger competitor to T/S Word. The only advantage 
DynaStar has over tfPShel is that it has its own builtin 
editor. It also comes with an external text formatter, 
df, which will work as WPShel's text formatter, by the 
way. WShel's advantages over DynaStar are that it has 
both a mouse and keyboard interface (DynaStar has no 
mouse interface) and WPShel includes other user 
custoiTiizable functions like a text file previewer and 
various spelling checker functions. DynaStar can, in 
fad, be used as l;'FShel*s editor, but in my opinion, that 



VPShei runs rings around T/S Word. WPShei much easier to 
set up and get going Kith than T/S Word is. T/S Edit 
works ok as WPSheTs editor (though not as well as some 
others, VED in particular), T/S Word's text formatter 
TSFMT doesn't work as a pull down menu option, but can be 
used in a Shell overlay window. T/S Spell, on the other 
hand works very well with WPShel, in fact, WPShel's 
spelling checker functions were explicitly designed to 
work exceptionally well with T/S SpelL 

I nave invested a great deal of time end effort into the 
design, development, and testing of WPShel, and for this 
reason, I have decided to release it only as a commercial 
product. The price is inexpensive, though, only $22. 

To use k'PShel to it's full extent, you will need an 
editor, a text formatter, a text file previewer utility, 
and a Spelling Checker. In an appendix in the 
dccumentation I mention that I have several Public Domain 
and Shareware editors, formatters, and text file preview 
utilities which I can send to you if you ask me for them. 
For legal reasons I cannot include them with WPShel, I 
also reference several commercial editors, formatters, 



and spelling checkers along with current prices and 
availability, which I recommend. 

Also, since WPShel uses the Multi-Vue Menu Bar interface 
and auto-follow mouse, the Windint module from your 
Multi-Vue disk is required in your bootlist. While WPShel 
can be run as a GShell application (an AIF an Icon are 
included for that purpose), it doesn't have to be. It 
will run perfectly fine in any window type from a Shell 
command. It also runs fine as an "autoex" system 
function, and included on the WPShel disk is a bootlist 
for creating a "turnkey" Word Processing Boot Disk, and 
the documentation contains step by step instructions i3n 
how to create this disk. 

Also, since overlay windows are used heavily, the "fast 
gfx" patches to GEFDF.V by Kevin Darling and Kent Hyers 
makes the flow of execution much faster and smoother. 

WPShel will EOT run on a I29K CoCo3. Since the next 
increment of memory available for the CoCo3 is the 255K 
"Ouarter-Meg"^ upgrade from Burke&Burke, the minimum 
amount of EAK required for WPShel is 256K. 

WPShel is ready for delivery new. So, if after reading 
this, ycu are still interested in WPShel, ie, want to 
purchase a copy, send se a check or money order for S22 



/T 



; f 



I pay all shipping and handling cosrsj to me. Or 
simply want a catalog of my current offerings of OS 
Level 2 and OSE-HM/1 software write to me at: 

CclcrSystems 

P.O. Box 5^:0 

Castle Havne, NC 28429 

USA 



(All software available on 5.25'^ SSDC, or 3.5" DSDD 
disk.) 

Zack Sessions, 



ooooooooooOOOOOOOOOOoooooooooo 



le Size? 



As gordon mentioned in his editorial, someone asked 
how you find the size of a file. Of course, everyone 
answers, use DIR E (or dir -e if you use the newer dir 
command), but when I looked at the question again, I was 
struck by the possibility that maybe the question should 
have been read as 'how do you find the size of ONE file?' 
Well, the dir command gives you a whole directory full, 
of course, and in HEXADECIMAL to boot, which may be more 
than you bargained for, If the file is a (single) 
module, you could use IDEST, Again, more information 
than you really needed. So, OK then, how DO you find it? 
Well, of course, use Bob Devries' magical FileSize 



prograFime. What's that? Never heard of it? Well that's 
not too surprising really, seeing as I lust wrote it. 

How does it work? Well, it is not too complicated. 
First it tries to open the file you asked for as a FILE, 
if that fails, it tries to open it as a DIRECTOEY (you 
never know.,.). Then it uses an (undocumented) 0S5 
I$GETSTT system call SS_FD, which reads the file 
descriptor, and stores it into a memory area (structure). 
When that is done, it reads the necessary bytes, four of 
them actually, to find the length of the file. The names 
in the structure 'fildes' which I used are defined in the 
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header file 'direct. h', vhich is on the C compiler disk method of doing the same thing, and 2. to provide 
in the DEFS directory. Then it uses the C printf call to portability to other 0S9 systems (e.g. OSK) 
print both the filename and the length, in DECIMAL. 

See, simple isn't it. Here's the C source code. 
Note the second version of the readfdO function. Regards, Bob Devries 

This is provided for two reasons, 1. to show an alternate 

/* FileSize */ 

/* Get the size of a file K' 

/* by Bob Devries 16 Nov 91 V 

^include (stdio.h) 
finchde (direct. h) 
finclude (os9.h) 

FILE *fp, *fopen(); /* declare file pointer etc */ 

struct fildes desc; /^ declare file descriptor structure V 

main(argc,argv) 
int argc; 
char *argv[I; 



pflinitO; I* we will be printing longs 



il 



if (argc != 2) { /^ not two comnana line args? V 

putsC^Usage: filesize (file^M; /^ tell user be erred ^/ 
exitfO); !•■ and exit nicelv */ 



if ((fp - fopeQisrgvill/r")) == iULLl ! /^ open read ^/ 

it ((fp = fGpen(argv[li,'dM! — KULLi ! /^ or open read dir */ 

prinrf i^Can't open ^cE. \n%argv[l]); /^ no? so say so */ 

exitlerrnol; /* ouit with error */ 



readfdO; /* go away and read the file desc into structure */ 
/* and report size. That's what we're here for \^ 

printf ("File Is is lid bytes iong.\n%argv[lj ,desc,fd fsizel; 



rea 
f 


^dfdO 








struct regi 


sters regs; 




regs 


.rg a = 


fileQo(fp); 




regs. 


,rg b = 


SS FD; 




regs. 


.rg X ~ 


Wesc; 




regs, 


,rg y - 


sizeof(de£c 




regs. 


,rg u = 


0; 




os9l 


;i GETSTT,^regs); 



/* set up temp struct to contain CPU regs ^1 

/* A = path number V 

i^ B = value for SSJD system call */ 

1^ I ~ pointer to structure V 

/* Y - length of struct V 

/* use I$GETSTT to do it V 
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alteraate readfdO fuaction 
if you have Carl Kreider's C Library 



readfdl 



getstat(SS FD,filena(fp),idesc,sizeof(desc)); 



ooooooooooOOOOOOOOOOoooooooooo 






O-^^m^S C:::^r^e: 



jyon^ 




A/atjci^^ OS^ Osms (^rooA 
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